/*
 * By: Werner Schuster (murphee)
 * 
 * Copyright (c) 2005-2006 Werner Schuster (murphee)
 * 
 * This file is part of the EclipseShell project. EclipseShell is subject 
 * to the Eclipse Public License (EPL) available at
 * http://www.eclipse.org/org/documents/epl-v10.php
 * or in the file /epl-v10.html in the source for other info
 * see the /eclipseshell.license file
 */
package net.sf.eclipseshell.extensions;


import java.io.Reader;

import org.eclipse.core.resources.IProject;
import org.eclipse.jface.text.ITextHover;
import org.eclipse.jface.text.contentassist.IContentAssistProcessor;

public interface IExecutionEnvironment {
	/**
	 * 
	 * @param code code to be executed in runtime environment
	 * @return the result of the evaluation, can be null
	 */
	public String execute(String code);
	/**
	 * 
	 * @param codeReader  reader where code (that is supposed to be executed) can be fetched 
	 * @return the result of the evaluation, can be null
	 */
	public String execute(Reader codeReader);
	
	/**
	 * Returns the @see IContentAssistProcessor for this execution environment. This is executed when the
	 * execution environment is first set up.
	 * The proj parameter is supposed to help define the
	 * scope of the script, ie. which project the script is executed in. If this is not applicable, then 
	 * null can be given. 
	 * 
	 * @param proj the Workspace IProject that this script belongs to OR null if none is available. 
	 * @return a ContentAssist Processor implementation or null if none is supplied
	 */
	public IContentAssistProcessor getContentAssistProcessor(IProject proj);
	
	public ITextHover getTextHover(IProject proj);
	
	/**
	 * Allows to customize the syntax highlighting.
	 * TODO: this should possibly return the Reconciler... but that needs to be installed/uninstalled
	 * in the TextViewer. See how this is done.
	 * 
	 * @return a tuple consisting of {IPresentationDamager, IPresentationRepairer} OR null 
	 */
	public Object[] getDamagerAndRepairer();

	/**
	 * This tells the ExecutionEnvironment to shutdown the environment, ie. stop execution, 
	 * and free any resources as far as possible. For external environments this could 
	 * mean stopping the execution and destroying the external process.
	 *
	 */
	public void shutdown();
	
	/**
	 * Set the public visible name for the Execution Environment instance.
	 * @param string
	 */
	public void setName(String string);
	
	// TODO: add a wrapInComment() method that takes a String and returns 
	// a String containing the argument in a comment formatted for the environments language;
	// needed to insert region delimiters;
}
